// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 注解`@Deprecated('expires when')`用于标记某功能已过时、被弃用、不再建议使用。
 *
 * 注解`@deprecated`是指，直到下一个未指定的正式版之前不建议使用的简写。
 *
 * `@Deprecated`的目的是，通知用户应该修改使用了某功能的代码，即使它目前运行正常。
 *
 * 一个过时的功能将在以后的时间被删除，可能是指定的注解的"expires"字段。
 * 这意味着，过时的功能不应该被使用，或者代码使用它时，可能在未来的某个时间点崩溃。
 * 如果代码使用了这些功能，应该重写代码，不使用过时的功能。
 *
 * 已过时的功能应该记录怎样实现相同的效果，让程序员知道怎么去重写代码。
 *
 * 注解`@Deprecated`适用于库、top-level顶层声明（变量、getters、setters、函数、类、typedefs）、
 * class-level类级声明（变量、getters、setters、方法、操作或构造函数，无论是否是静态）、
 * 命名可选参数和位置可选参数。
 *
 * Deprecation具有传递性:
 *
 *  - 如果库过时，那么所有成员也过时。
 *  - 如果类过时，那么所有成员也过时。
 *  - 如果变量过时，那么它的隐式的getter和setter方法也过时。
 *
 * 处理Dart源码的工具会报告提示信息的情况：
 * - 代码导入了一个过时的库
 * - 代码导出了一个过时的库，或非过时库的一些过时的成员
 * - 代码静态地使用了一个过时的声明
 * - 对于对象的静态类型，代码动态地使用带有静态已知类型的对象的一个成员，而成员已过时
 * - 对于对象的静态类型，代码带参数动态调用方法，而对应的可选参数过时
 *
 * 如果在库、类或方法的内部使用deprecated，那么它本身也是过时的，
 * 对此工具不应该为使用者操心。一个过时的功能估计使用了其他过时的功能。
 */
class Deprecated {
  /**
   * 过时的、预计将被删除的功能的描述
   */
  final String expires;

  /**
   * 创建一个Deprecated注解，并且指定注解的功能过期。
   *
   * [expires]参数应该是程序员可读的，并且应该声明何时被注解的功能将被删除。
   * 这是可以被指定为日期、Release版本号或相对于其他的一些修改（如“when bug 4418 is fixed”）。
   */
  const Deprecated(String expires) : this.expires = expires;

  String toString() => "Deprecated feature. Will be removed $expires";
}

class _Override {
  const _Override();
}

/**
 * 标记一个功能在下一个Release版本前为[Deprecated]。
 */
const Deprecated deprecated = const Deprecated("next release");

/**
 * 注解`@override`将标记和重写一个实例的成员，并且与父类的成员名称相同。
 *
 * 该注解适用于实例方法、getters和setters、以及实例的字段
 * （这时意味着字段隐式的getter和setter被标记为重写，但是字段本身不是）。
 *
 * `@override`的目的是捕获父类重命名成员的位置，
 * 而独立的子类用于重写成员，并且可以继续使用父类的实现。
 *
 * 如果父类或接口被注解的成员被继承而没有声明，编辑器或类似的工具针对程序员，会输出提示信息。
 *
 * 使用注解`@override`正确的情况是，方法所在的父类不在程序员的控制之下，
 * 父类可能在不同的库或包中，并且不稳定。
 * 在任何情况下，`@override`的使用是可选的。
 *
 * 例如，有意地不在Dart平台的库中使用注解，因为它们只依赖于自身。
 */
const Object override = const _Override();

class _Proxy {
  const _Proxy();
}

/**
 * 注解`@proxy`将标记一个类作为实现的成员，动态地通过`noSuchMethod`。
 *
 * 该注解适用于任何类。它通过父类和接口被继承。
 *
 * 如果类被标注为`@proxy`，或它实现了任何被标注的类，
 * 那么这个类的任何成员将被认为实现了静态类型分析。
 * 因此，访问任何类未实现的对象的成员，或使用与声明不同数量的参数调用方法时，
 * 产生的并不是一个静态类型警告。
 *
 * 注解并不会改变被标注的类的实现，如果将未实现的静态类型对象分配给变量，
 * 并不会阻止静态警告。
 *
 * 禁止警告只会影响成员访问的静态类型警告。
 * 对象的运行时类型不受影响。
 * 它并不是实现了任何特殊的接口，因此在Checked模式中，
 * 将它分配给一个类型的变量可能会失败。
 * 使用`is`操作符对类型进行测试时，将只返回true，它实际上是implements或extends。
 * 通常，访问一个未被类实现的成员会使`noSuchMethod`方法被调用，
 * `@proxy`注解只是意向处理（一些）`noSuchMethod`使调用更加优雅。
 *
 * 被标记为`@proxy`的类应该重写[Object]声明的`noSuchMethod`方法。
 *
 * `@proxy`的目的是在编译时，创建一个或多个未知类型对象。
 * 如果在编译时类型可知，类可以编写那些类型的实现。
 */
const Object proxy = const _Proxy();
